****************Digisalt IPS-BugTracker 1.0 (c) 2007 by FloBo ***************

Author   : FloBo
Version  : 1.0
Date     : ??.??.2007

...

1. Disclaimer
2. Installation
3. Contents of the archieve
4. Description / How to use
5. Tool history





1. Disclaimer

This tool is not related to any company at all. It's just some little
program I wrote, to track down some nasty bugs I had in my IPS while trans-
lating Lufia1 into German. This tool was never meant to be released, and its
not polished at all, so don't bug me if it doesn't do exactly what it should
do. Nevertheless, I found it on an old HDD a few days ago and thus it will
make its way to the internet. As I do know it is not finished and I expect
there might at least be some bugs in it, I included the C souce for it so
you can fix the tool on your own. Please understand that I don't want to
furtherly look into problems related to that tool. You'll just have to do
it on your own. Also be aware, that I am not responsible for any damage
that might be caused by this tool. You're using it on your own risk. You
have been warned. Don't blame me, if anything goes wrong.


2. Installation

There's no real installation for this tool. Just extract the exe file to
any directory you wish. Double clicking on the exe just displays the instruc-
tions on how to use it so you'll need the commandline to pass some arguments.


3. Contents of the archieve

Within the archieve, there should be (not more and not less than) four files.
_____________________________________________________
IpsBugTracker.exe.....the tool
Liesmich.txt..........the german readme-file
Readme.txt............the english readme-file
main.c................the sourcecode
_____________________________________________________
This archive may be furtherly distributed without any further permissions as
long as it is being done free of charge and unchanged. It is not allowed to
change the archive content. Adding/leaving out any of the files and furtherly
redistributing the file is prohibited if no explicit permission has been
granted to do so in advance. If you still wish to redistribute the archive
with altered content, please write an email to
webmaster_at_digisalt_dot_de
Subject: ipsbugtracker

If you want to use the sourcecode provided in your own tools and/or modify
it, make sure to give credit where due and also send a short mail to the
email address given above. I'm always curious to see new things being done
with my work :)


4. Description / How to use

This is the first version of the Digisalt IPS-Bugtracker. I wrote it during
the process of creating the German Translation of Lufia & the Fortress of
Doom. As mentioned above, the tool wasn't intended for public release, so
don't expect a perfectly polished and bug-free tool (though it always did its
job for me just fine). Nevertheless, soucecode is included on that one as it
isn't maintained by myself so feel free to try and fix the bugs contained on
your own. The tool actually can help you when you're facing the following
problem. Imagine you have a translation/hack/something you already put a LOT
of effort into. You may have saved it in various versions while developing it.
Suddenly, you notice, that it now contains a bug that makes the game crash
horribly and this isn't easily fixable. Some of the older versions worked
fine, though. That means that the bug is caused by some of the modifinaction
deltas between the current version and the older ones. You can isolate the
deltas between the versions of your rom by creating an IPS patch. The less
those deltas are, the less big in size the IPS patch will be. Another
scenario where this tool might come handy is the following: you regularly
create backups of your hack/translation/whatever on let's say a usb-stick.
Unfortunately, copying the file back and forth between your computer and the
usb-drive has damaged it... That means one or more bytes have been altered
unintentionally. If this then causes your game to crash, you'll also want to
find out which of the alterations make it crash. So you take an older,
working copy of the rom and the buggy one and also create an IPS patch to
narrow down the area of where to search for the bug.
There might be more scenarios but in any case, you'll need an IPS-patch
causing the bug to occur. As you might know (or not), IPS patches are created
by different records. Each record describes either "write this byte-sequence
to offset XYZ" or "write this byte XYZ times the rom starting at offset X",
the former being regular records and the latter being RLE-compressed records.
In any case, every IPS-patch is created by those records. And in the optimum
case, it is one of those records alone causing the error to occur. This tool
can help you to identify the faulty record and to show what data it modifies
so you can go ahead and try to fix it at that position also.
It does so in an semi-automated process. Let's assume we have an IPS
containing seven records. The tool will go and grab the non-error-prone rom
and patch it with the first half of the records (that is it will likely use
record 1 - 4). Having created a patched rom, it'll ask you to test the rom
weather or not the bug still occurs (at this point, it might be handy if you
have your emulator of choice available and in the optimum case also a
savestate directly before the bug occurs). Having tested, you can then
indicate that the error occurred or not by typing y (for yes, it occurred) or
n (for no, everything was fine). Let's assume it didn't occur. That means:
records 1 - 4 of the seven records were not the problem. So the tool will
once again patch the unaltered rom with the IPS records. But knowing that
records 1 - 4 were not bad, it only cosiders the other records (5 - 7) for
the next iteration. To furtherly narrow down, it'll only take half of the
remaining records again asking you to test and verify if the bug occurred.
If not, it'll take half of the remaining half and so on and so forth.
Visually, the process can be seen like this:

IPS-records used in first iteration:

  1               n/2  n/2+1             n      
  |XXXXXXXXXXXXXXXXXX||------------------|

IPS-records used in second iteration (if yes was selected):
  
  1     n/4  n/4+1  n/2
  |XXXXXXXX||--------|--------------------

IPS-records used in second iteration (if no was selected):

                    n/2+1 3*n/4 3*n/4+1  n
  --------------------|XXXXXXXX||--------|

This process is done until only optimally one single IPS record remains. This
will then be printed to the console telling you where to look at for fixing
the bug. The process was chosen to minimize the number of iterations (and
thus unnerving you with "please test if the bug still occurred").


5. Tool history

Digisalt IPS-BugTracker 1.0 - 20.12.2009 - initial release


*******************************End of file**********************************
